---
title: Set up AWS Accounts
description: A simple and secure guide to setting up AWS accounts.
---

Unsurprisingly there are multiple ways to set up AWS accounts. And unfortunately the default process misses a few things that'll likely make this a lot easier for your team.

:::tip
If you are using IAM users or have credential files, this guide is for you.
:::

---

The ideal setup is to have multiple AWS accounts grouped under a single AWS Organization. While your team authenticates through SSO to access the Console and the CLI.

While this sounds complicated, it's a one time process that you'll never have to think about again.

Let's get started.

---

## Management account

The first step is to [**create a management account**](https://portal.aws.amazon.com/billing/signup?type=enterprise#/start/email).

1. Start by using a **work email alias**. For example `aws@acme.com`. This'll forward to your real email. It allows you to give other people access to it in the future.
2. The **account name** should be your company name, for example `acme`.
3. Enter your **billing info** and **confirm your identity**.
4. Choose **basic support**. You can upgrade this later.

Once you're done you should be able to login and access the AWS Console.

These credentials are overly powerful. You should rarely ever need them again. Feel free to throw away the password after completing this guide. You can always do a password reset if it's needed.

:::tip
The Management account is what you'll use to manage the users in your organization.
:::

This account won't have anything deployed to it besides the IAM Identity Center which is how we'll manage the users in our organization.

---

### AWS Organization

Next, we'll create an organization. This allows you to manage multiple AWS accounts together. We'll need this as we create separate accounts for dev and prod.

Search **AWS Organization** in the search bar to go to its dashboard and click **Create an organization**.

You'll see that the management account is already in the organization.

---

### IAM Identity Center

Now let's enable IAM Identity Center.

1. Search **IAM Identity Center** and go to its dashboard. Click **Enable**.

   :::note
   Make a note of the region you're in for the IAM Identity Center.
   :::
   
   This'll be created in one region and you cannot change it. However, it doesn't matter too much which one it is. You'll just need to navigate to that region when you are trying to find this again.

2. Click **Enable**. This will give your organization a unique URL to login.

   :::note
   Make a note of the URL that IAM Identity Center gives you.
   :::

   This is auto-generated but you can click **Customize** to select a unique name. You'll want to bookmark this for later.

---

## Root user

Now we'll create a root user in IAM Identity Center.

1. Click **Users** on the left and then **Add user** to create a user for yourself. Make your username your work email, for example `dax@acme.com`, and fill out the required fields.
2. Skip adding the user to groups.
3. Finish creating the user.

We've created the user. Now let's give it access to our management account.

---

### User access

Go to the left panel and click **AWS Accounts**.

1. Select your management account. It should be tagged as such. And click **Assign users or groups**.
2. Select the Users tab, make sure your user is selected and hit **Next**.
3. Now we'll need to create a new permission set. We need to do this once. Click **Create permission set**.
4. In the new tab select **Predefined permission set** and **AdministratorAccess**. Click **Next**.
5. Increase the session duration to 12 hours. This is the most convenient option. Click **Next** and then **Create**.
6. Close the tab, return to the previous one and hit the refresh icon. Select **AdministratorAccess** and click **Next** and then **Submit**.

This might seem complicated but all we did was grant the user an _AdministratorAccess role_ into the management account.

Now you're ready to log in to your user account.

---

### Login

Check your email and you should have an invite.

1. **Accept the invite** and **create a new password**. Be sure to save it in your password manager. This is important because this account has access to the management account.

   :::note
   If you already have an SSO provider, like Google you can allow your team to _Login with Google_. Let us know if you'd like us to document that as well.
   :::

2. Sign in and you should see your organization with a **list of accounts** below it.

   You currently only have access to the management account we created above. So click it and you should see the AdministratorAccess role.

3. Click **Management Console** to login to the AWS Console.

You're now done setting up the root user account!

---

## Dev and prod accounts

As mentioned earlier, your management account isn't meant to deploy any resources. It's meant to manage users.

So a good initial setup is to create separate `dev` and `production` accounts. This helps create some isolation. The `dev` account will be shared between your team while the `production` account is just for production.

You can also create a staging account or an account per developer but we'll start simple.

---

Navigate back to **AWS Organizations** by searching for it.

1. Click **Add an AWS account**.
2. For the account name append `-dev` to whatever you called your management account. For example, `acme-dev`.
3. For the email address choose a new email alias. If you're using Google for email, you can do `aws+dev@acme.com` and it'll still go to your `aws@acme.com` email.
4. Click **Create AWS account**.

**Repeat this step** and create the `-production` as well. So you should now have an `acme-dev` and an `acme-production`.

It'll take a few seconds to finish creating.

---

### Assign users

Once it's done head over to **IAM Identity Center** to grant your user access to these accounts.

1. Select the **AWS Accounts** tab on the left.
2. Select your newly created `acme-dev` and `acme-production` accounts and click **Assign users or groups**.
3. In the **Users** tab select your user and click **Next**.
4. Select the **AdministratorAccess** permission set and click **Next** and **Submit**.

Now you can go back to your SSO URL. You should now see three different accounts and you'll be able to login to whichever one you want.

:::tip
You can find your SSO URL by clicking **Dashboard** on the left.
:::

You can create additional users and add them to these accounts using the steps above. You can reuse the role or create one with stricter permissions.

Next, let's configure the AWS CLI and SST to use this setup.

---

## Configure AWS CLI

The great thing about this setup is that you no longer need to generate AWS IAM credentials for your local machine, you can just use SSO. This is both simpler and more secure.

:::tip
You can [download](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) the AWS CLI from the AWS docs.
:::

All you need is a single configuration file for the AWS CLI, SST, or any random scripts you want to run. And there will never be any long lived credentials stored on your machine.

---


1. Add the following block to a `~/.aws/config` file.

   ```bash title="~/.aws/config"
   [sso-session acme]
   sso_start_url = https://acme.awsapps.com/start
   sso_region = us-east-1
   ```

   Make sure to replace the `sso_start_url` with your SSO URL that you bookmarked. And set the region where you created IAM Identity Center as the `sso_region`.

2. Add an entry for each environment, in this case `dev` and `production`.

   ```bash title="~/.aws/config"
   [profile acme-dev]
   sso_session = acme
   sso_account_id = <account-id>
   sso_role_name = AdministratorAccess
   region = us-east-1

   [profile acme-production]
   sso_session = acme
   sso_account_id = <account-id>
   sso_role_name = AdministratorAccess
   region = us-east-1
   ```

   You can find the account ID from your SSO login url. If you expand the account you will see it listed with a `#` sign.

   The region specified in the config is the default region that the CLI will use when one isn't specified.

   :::tip
   With this setup you won't need to save your AWS credentials locally.
   :::

   And the role name is the one we created above. If you created a different role, you'd need to change this.

3. Now you can login by running.

   ```bash
   aws sso login --sso-session=acme
   ```

   This'll open your browser and prompt you to allow access. The sessions will last 12 hours, as we had configured previously.

   If you're using Windows with WSL, you can add a script to open the login browser of the host machine.
   
   <details>
   <summary>View script</summary>

   ```sh title="login.sh"
   #!/bin/bash

   if grep -q WSL /proc/version; then
      export BROWSER=wslview
   fi

   aws sso login --sso-session=acme
   ```

   </details>

4. Optionally, for Node.js projects, it can be helpful to add this to a `package.json` script so your team can just run `npm run sso` to login.

   ```json title="package.json"
   "scripts": {
     "sso": "aws sso login --sso-session=acme"
   }
   ```

5. Finally, test that everything is working with a simple CLI command that targets your dev account.

   ```bash
   aws sts get-caller-identity --profile=acme-dev
   ```

Next, let's configure SST to use these profiles.

---

## Configure SST

In your `sst.config.ts` file check which stage you are deploying to and return the right profile.

```ts title="sst.config.ts" {8}
export default $config({
  app(input) {
    return {
      name: "my-sst-app",
      home: "aws",
      providers: {
        aws: {
          profile: input.stage === "production" ? "acme-production" : "acme-dev"
        }
      }
    };
  },
  async run() {
    // Your resources
  }
});
```

This will use the `acme-production` profile just for production and use `acme-dev` for everything else.

:::note
The `AWS_PROFILE` environment variable will override the profile set in your `sst.config.ts`.
:::

If you've configured AWS credentials previously through the `AWS_PROFILE` environment variable or through a `.env` file, it will override the profile set in your `sst.config.ts`. So make sure to remove any references to `AWS_PROFILE`.

Now to deploy to your production account you just pass in the stage.

```bash
sst deploy --stage production
```

And we are done!

---

To summarize, here what we've created:

1. A management account to manage the users in our organization.
2. A root user that can login to the management account.
3. Dev and production accounts for our apps.
4. Finally, given the root user access to both accounts.

You can extend these by adding more users, or adding additional accounts, or modifying the roles you grant.
